# GUI与扩展驱动库

```{admonition} 本文引用的文件
:class: note

- `gui.py`
- `sdcard.py`
- `bluebit.py`
- `parrot.py`
- `ds18x20.py`
- `machine_servo.c`
- [sdcard.rst（ESP32-S3 API文档）](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）](../../../../products/mpython/library/mPython/sdcard.rst)
- [parrot.rst（拓展板说明）](../../../../products/mpython/extboard/parrot.rst)
- `sdcard示例`
```

## 产品概述
本章节面向GUI图形绘制、SD卡存储、Bluebit扩展板驱动、Parrot鹦鹉扩展板驱动、DS18X20温度传感器以及舵机控制等常用外设的API参考。这些模块覆盖显示、存储、传感、执行器与扩展板生态，适用于掌控板及ESP32-S3系列产品的教学与创客项目。

- 目标用户：K12创客教育、电子爱好者、嵌入式初学者
- 核心价值：提供统一易用的Python接口，屏蔽底层硬件细节，快速实现交互界面、数据记录、环境感知与机械控制
- 适用场景：数据可视化、设备状态展示、离线数据存储、传感器采集、电机与舵机控制、红外遥控、语音合成等

## 核心业务流程
- 图形绘制流程：初始化显示对象 → 调用绘图API（点线面、文本、图像、二维码）→ 刷新显示
- SD卡流程：配置SPI与CS引脚 → 创建SDCard对象 → 挂载文件系统 → 使用标准文件操作读写
- Bluebit流程：通过I2C/ADC/UART访问各类传感器与显示模块（温湿度、颜色、光线、数码管、矩阵屏、MIDI等）
- Parrot流程：通过I2C控制电机速度/LED亮度、读取电池电压；通过IR类进行红外编码发送、学习与停止
- DS18X20流程：单总线读取温度值
- 舵机流程：创建Servo对象 → 设置角度或脉宽 → 控制PWM输出

```text
flowchart TD
A["应用层"] --> B["GUI绘制"]
A --> C["SD卡存储"]
A --> D["Bluebit扩展"]
A --> E["Parrot扩展"]
A --> F["DS18X20温度"]
A --> G["舵机控制"]
B --> H["framebuf/屏幕驱动"]
C --> I["SPI + FAT挂载"]
D --> J["I2C/ADC/UART"]
E --> K["I2C/IR"]
F --> L["单总线"]
G --> M["LEDC PWM"]
```

## 功能模块清单
- GUI（图形绘制）
  - UI：进度条、条形图、二维码生成
  - multiScreen：多帧切换与指示符
  - Clock：模拟时钟绘制
  - Image：PBM/BMP图片解码为FrameBuffer
- SD卡
  - SDCard(spi, cs)：初始化并挂载FAT文件系统
- Bluebit（扩展板驱动）
  - 温度：Thermistor/LM35
  - 按键：joyButton/joyButton1
  - 温湿度：SHT20
  - 颜色：Color（RGB/HSV）
  - 光线：AmbientLight
  - 超声波：Ultrasonic
  - 数码管：SEGdisplay（TM1650/HT16K33）
  - 点阵：Matrix（HT16K33）
  - LCD1602：字符显示与光标控制
  - MIDI：音量、音色、音符控制
  - 其他：GPS、气压、PM2.5、心率、手势、太阳能等子模块集成
- Parrot（鹦鹉扩展板）
  - 电机：set_speed/get_speed
  - LED灯：led_on/led_off
  - 电池：get_battery_level
  - 红外：IR_encode.encode_nec/encode_raw、IR.send/learn/get_learn_data/stop_send
- DS18X20（温度传感器）
  - 单总线温度读取（基于MicroPython onewire驱动）
- 舵机（Servo）
  - Servo(pin, freq=50, angle=-1, min_us=750, max_us=2250, actuation_range=180)
  - write_angle(angle)、write_us(us)、freq()、duty()、init()/deinit()

**Section sources**
- `gui.py:7-48`
- `gui.py:49-79`
- `gui.py:81-142`
- `gui.py:144-224`
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `bluebit.py:47-123`
- `bluebit.py:125-180`
- `bluebit.py:181-212`
- `bluebit.py:214-275`
- `bluebit.py:277-323`
- `bluebit.py:324-413`
- `bluebit.py:422-499`
- `bluebit.py:507-562`
- `bluebit.py:573-751`
- `bluebit.py:754-800`
- `parrot.py:20-57`
- `parrot.py:59-108`
- `parrot.py:112-187`
- `parrot.py:189-243`
- `machine_servo.c:137-221`
- `machine_servo.c:223-250`
- `machine_servo.c:252-352`

## 数据与状态
- GUI
  - UI进度条/条形图：以百分比作为输入，内部计算填充宽度/高度
  - multiScreen：维护当前帧索引与帧列表，支持nextScreen切换
  - Clock：维护中心坐标与半径，实时获取系统时间绘制指针
  - Image：根据文件头识别格式（PBM/PBM或BMP），解析像素数据为FrameBuffer
- SD卡
  - 依赖SPI与CS引脚，需FAT/FAT32格式化；挂载后使用标准文件API
- Bluebit
  - 各传感器返回标准化数值（如温度℃、湿度%、光照lux、距离cm、磁场强度、航向角等）
  - 显示模块（数码管/矩阵/LCD1602）维护缓冲区与显示状态
- Parrot
  - 电机速度缓冲：_speed_buf缓存最近一次速度，便于查询
  - 红外：学习成功后返回布尔状态，可获取编码数据buff
- DS18X20
  - 单总线时序读取温度，异常时返回None（由封装决定）
- 舵机
  - 维护通道、频率、脉宽范围、角度范围；写角度/脉宽时校验范围并更新占空比

```text
classDiagram
class UI {
+ProgressBar(x,y,width,height,progress)
+stripBar(x,y,width,height,progress,dir,frame)
+qr_code(str,x,y,scale)
}
class multiScreen {
+drawScreen(index)
+nextScreen()
}
class Clock {
+settime()
+drawClock()
+clear()
}
class Image {
+load(path,invert)
}
UI --> "uses" FrameBuffer
multiScreen --> "uses" FrameBuffer
Clock --> "uses" FrameBuffer
Image --> "returns" FrameBuffer
```

**Diagram sources**
- `gui.py:7-48`
- `gui.py:49-79`
- `gui.py:81-142`
- `gui.py:144-224`

**Section sources**
- `gui.py:7-224`
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `bluebit.py:47-800`
- `parrot.py:20-243`
- `machine_servo.c:137-352`

## 关键约束与边界
- GUI
  - 依赖framebuf与具体屏幕驱动；二维码生成使用adafruit_miniqr，注意内存占用
  - 图像加载仅支持部分格式（PBM/PBM与1位BMP），超出将抛出类型错误
- SD卡
  - 必须正确连接SPI引脚与CS；卡需FAT/FAT32格式化；挂载路径需唯一
  - 频繁写入可能影响寿命，建议批量写入与合理刷新策略
- Bluebit
  - 多数模块通过I2C通信，需确保地址与上电时序；部分模块需要延时等待转换完成
  - ADC读取需注意衰减配置与分压电路参数
- Parrot
  - 电机速度与LED亮度有范围限制（速度-100~100，亮度0~100）
  - 红外学习需在5秒内按住被学习按键；重复码发送需显式停止
- DS18X20
  - 单总线时序严格，需保证总线空闲与复位序列；多设备时需处理ROM地址
- 舵机
  - 角度与脉宽需落在min_us~max_us范围内；频率变更受分辨率限制
  - 通道资源有限，避免同时过多Servo实例导致冲突

```text
sequenceDiagram
participant App as "应用"
participant SD as "SDCard"
participant SPI as "SPI"
participant FS as "文件系统"
App->>SD : 构造(SPI, CS)
SD->>SPI : 初始化SPI
App->>FS : os.mount(sd, "/sd")
FS-->>App : 挂载成功
App->>FS : open("/sd/test.txt","w")
FS-->>App : 文件句柄
App->>FS : write("Hello world!")
FS-->>App : 写入完成
```

**Diagram sources**
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `sdcard示例:1-14`

**Section sources**
- `gui.py:144-224`
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `bluebit.py:47-800`
- `parrot.py:20-243`
- `machine_servo.c:137-352`

## 详细API参考

### GUI（图形绘制）
- UI
  - ProgressBar(x, y, width, height, progress)：绘制圆角进度条
  - stripBar(x, y, width, height, progress, dir=1, frame=1)：水平/垂直条形图
  - qr_code(str, x, y, scale=2)：生成二维码并绘制到屏幕
- multiScreen
  - drawScreen(index)：绘制指定帧与底部指示符
  - nextScreen()：切换到下一帧
- Clock
  - settime()：从系统时间更新时分秒
  - drawClock()：绘制表盘与时分秒针
  - clear()：清除时钟区域
- Image
  - load(path, invert=0)：加载PBM/PBM或1位BMP，返回FrameBuffer

```text
flowchart TD
Start(["开始"]) --> LoadImg["Image.load(path)"]
LoadImg --> Format{"格式?"}
Format --> |PBM/PBM| DecodePBM["_pbm_decode()"]
Format --> |BMP| DecodeBMP["_bmp_decode()"]
DecodePBM --> FB["FrameBuffer"]
DecodeBMP --> FB
FB --> End(["结束"])
```

**Diagram sources**
- `gui.py:144-224`

**Section sources**
- `gui.py:7-48`
- `gui.py:49-79`
- `gui.py:81-142`
- `gui.py:144-224`

### SD卡（sdcard）
- SDCard(spi, cs)：创建并初始化SD卡对象
- 挂载：os.mount(sd, "/sd")
- 文件操作：open/read/write/close等标准API

```text
sequenceDiagram
participant App as "应用"
participant SPI as "SPI"
participant SD as "SDCard"
participant OS as "os"
App->>SPI : 配置引脚与波特率
App->>SD : SDCard(spi, cs)
App->>OS : mount(sd, "/sd")
OS-->>App : 挂载结果
App->>OS : open("/sd/test.txt","w")
OS-->>App : 文件句柄
App->>OS : write("Hello world!")
OS-->>App : 关闭
```

**Diagram sources**
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `sdcard示例:1-14`

**Section sources**
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `sdcard示例:1-14`

### Bluebit（扩展板驱动）
- 温度
  - Thermistor(pin, series_resistor, nominal_resistance, nominal_temperature, b_coefficient, high_side=True)：NTC温度测量
  - LM35(pin)：线性温度传感器
- 按键
  - joyButton(pin)：四键检测（A/B/C/D）
  - joyButton1(pin)：五向按键（up/down/right/left/mid）
- 温湿度
  - SHT20(i2c=i2c)：temperature()/humidity()
- 颜色
  - Color(i2c=i2c)：getRGB()/getHSV()
- 光线
  - AmbientLight(i2c=i2c)：getLight()
- 超声波
  - Ultrasonic(i2c=i2c)：distance()
- 数码管
  - SEGdisplay(i2c=i2c)：numbers(x)/Clear()
- 点阵
  - Matrix(i2c=i2c)：pixel/fill/text/show
- LCD1602
  - Print/Cursor/Blink/display/move_left/move_right/createChar等
- MIDI
  - volume/instrument/note等属性与方法

**Section sources**
- `bluebit.py:47-123`
- `bluebit.py:125-180`
- `bluebit.py:181-212`
- `bluebit.py:214-275`
- `bluebit.py:277-323`
- `bluebit.py:324-413`
- `bluebit.py:422-499`
- `bluebit.py:507-562`
- `bluebit.py:573-751`
- `bluebit.py:754-800`

### Parrot（鹦鹉扩展板）
- 电机
  - set_speed(motor_no, speed)：设置M1/M2速度（-100~100）
  - get_speed(motor_no)：查询当前速度
- LED灯
  - led_on(no, brightness=50)：点亮并设置亮度（0~100）
  - led_off(no)：关闭
- 电池
  - get_battery_level()：返回电量mV
- 红外
  - IR_encode.encode_nec(user_code, command_code)：NEC编码
  - IR_encode.encode_raw(carry_freq, len, repeat_pos, code, data)：自定义编码
  - IR.send(buff, repeat_en=0)：发送编码数据
  - IR.learn(wait=True)：学习红外信号
  - IR.get_learn_data()：获取学习后的编码数据
  - IR.stop_send()：停止重复码发送

```text
sequenceDiagram
participant App as "应用"
participant Parrot as "parrot"
App->>Parrot : set_speed(MOTOR_1, 50)
Parrot->>Parrot : i2c.writeto(0x10, [motor_no, speed])
App->>Parrot : IR.send(buff)
Parrot->>Parrot : i2c.writeto(16, [0x04, repeat_en] + buff)
App->>Parrot : IR.learn(True)
Parrot->>Parrot : i2c.writeto(16, 0x06)
Parrot-->>App : True/False
```

**Diagram sources**
- `parrot.py:20-57`
- `parrot.py:59-108`
- `parrot.py:112-187`
- `parrot.py:189-243`

**Section sources**
- [parrot.rst（拓展板说明）:1-106](../../../../products/mpython/extboard/parrot.rst)
- `parrot.py:20-243`

### DS18X20（温度传感器）
- 基于onewire协议的单总线温度读取
- 典型用法：初始化单总线 → 搜索设备 → 读取温度
- 注意事项：总线时序严格，多设备需区分ROM地址

**Section sources**
- `ds18x20.py:1`

### 舵机（Servo）
- 构造函数：Servo(pin, freq=50, angle=-1, min_us=750, max_us=2250, actuation_range=180)
- 方法：
  - write_angle(angle)：设置角度（0~actuation_range）
  - write_us(us)：设置脉宽（min_us~max_us）
  - freq()：获取/设置PWM频率
  - duty()：获取/设置占空比
  - init()/deinit()：初始化/释放通道

```text
flowchart TD
S["创建Servo(pin)"] --> Init["初始化LEDC定时器与通道"]
Init --> SetAngle{"是否设置angle?"}
SetAngle --> |是| CalcUS["计算us = min_us + angle*range/actuation_range"]
CalcUS --> SetDuty["设置占空比并更新"]
SetAngle --> |否| Wait["等待后续调用"]
SetDuty --> End["结束"]
Wait --> End
```

**Diagram sources**
- `machine_servo.c:137-221`
- `machine_servo.c:316-352`

**Section sources**
- `machine_servo.c:137-221`
- `machine_servo.c:223-250`
- `machine_servo.c:252-352`

## 性能考虑
- GUI
  - 大量图形绘制时注意gc.collect()时机与内存碎片
  - 二维码缩放比例越大，像素点越多，渲染耗时增加
- SD卡
  - 高频写入会加速磨损，建议合并写入与减少小文件频繁操作
  - 挂载后文件IO遵循操作系统缓存策略，适时flush或close
- Bluebit
  - I2C传感器读取需预留转换时间（sleep_ms），避免读回无效数据
  - ADC采样速率与精度需权衡，必要时降低采样频率
- Parrot
  - 电机频繁启停会产生冲击电流，建议平滑调速
  - 红外学习过程阻塞，非阻塞模式需自行轮询状态
- DS18X20
  - 单次转换约750ms（取决于分辨率），避免阻塞主循环
- 舵机
  - PWM频率过低可能导致抖动，过高则分辨率受限；推荐50Hz左右

[本节为通用指导，不直接分析具体文件]

## 故障排查
- GUI
  - 图片格式不支持：检查是否为PBM/PBM或1位BMP
  - 二维码空白：确认字符串编码与scale参数
- SD卡
  - 挂载失败：检查SPI引脚与CS是否正确；确认卡已格式化
  - 无法写入：检查权限与文件系统类型
- Bluebit
  - 传感器无响应：检查I2C地址与供电；增加延时
  - ADC读数异常：检查衰减配置与外部电路
- Parrot
  - 电机不转：检查速度范围与电源能力；确认I2C通信正常
  - 红外学习失败：确保在5秒内按住按键；重试或更换遥控器
- DS18X20
  - 读数为None：检查单总线接线与上拉电阻
- 舵机
  - 角度无效：检查angle是否在actuation_range内；脉宽是否在min_us~max_us

**Section sources**
- `gui.py:144-224`
- [sdcard.rst（ESP32-S3 API文档）:18-39](../../../../products/mpython-s3/5_api/library/mPython/sdcard.rst)
- [sdcard.rst（mPython API文档）:18-39](../../../../products/mpython/library/mPython/sdcard.rst)
- `bluebit.py:47-800`
- `parrot.py:20-243`
- `machine_servo.c:137-352`

## 结论
本参考覆盖了GUI绘制、SD卡存储、Bluebit与Parrot扩展板驱动、DS18X20温度传感器与舵机控制的核心API与使用要点。通过统一的Python接口，开发者可以快速构建交互界面、扩展存储、采集环境与运动控制等功能。实际项目中应关注时序、电源与资源分配，以获得稳定可靠的运行效果。

[本节为总结性内容，不直接分析具体文件]